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This is a major revision of, and obsoletes, GC21 -7566-0 and Technical Newsletter 
GN21-7657. This manual has been extensively revised and should be reviewed in 
its entirety. 

Information concerning IBM System/3 Model 15 has been added to the manual. The 
entire section entitled Chapter 5. Using Console Devices has been removed from 
this manual. The KEY (Model 6 only) and DSPLY operation codes, formerly described 
in Chapter 5, are described in your RPG II reference manual. For information 
concerning the RPG II Inquiry facility (Rollout/Rollin), also formerly described in 
Chapter 5, see Related Publications, listed in the Preface. 

Changes are periodically made to the information herein; before using this publication 
in connection with the operation of IBM systems, refer to the IBM System/3 
Bibliography, GC20-8080, for the editions that are applicable and current. 

Use this publication only for the purposes stated in the Preface. 

Publications are not stocked at the address below. Requests for copies of IBM 
publications and for technical information about the system should be made to your 
IBM representative or to the IBM branch office serving your locality. 
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publication. If the form has been removed, address your comments to IBM Corporation, 
Publications, Department 245, Rochester, Minnesota 55901. Comments become the 
property of IBM. 
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Preface 



This manual explains the RPG II specifications necessary 
to process disk files using the IBM System/3 Model 6, 
Model 10 Disk System, and Model 15. The following 
types of files are discussed: 



Related Publications 

These publications are recommended for additional 
reference: 



• Sequential 

• Indexed 

• Direct 



General System/3 

• IBM System /3 Disk Concepts and Planning Guide, 
GC21-7571 



• Record Address 

Included are examples of creating and maintaining each 
of these file types. For information on how this pub- 
lication should be read, see How to Use This Publication, 
following the table of contents. 

This manual is intended for programmers who have a 
basic knowledge of the RPG II language, including the 
ability to describe sequential and indexed files as 
input files. The reader must be familiar with the 
information presented in the IBM System/3 Disk Con- 
cepts and Planning Guide, GC21 -7571 . 



Note: For detailed information concerning multi- 
volume disk files — concepts; Operation Control Lan- 
guage considerations; RPG II processing — see the 
publications listed under Related Publications which 
are appropriate for your System/3 model. 



RPG II References 

• IBM System/3 Model 6 RPG II Reference Manual, 
SC21-7517 

• IBM System/3 RPG II Reference Manual, SC21 -7504 



OCL References 

• IBM System/3 Models 8 and 10 System Control 
Programming Reference Manual ', GC21-7512 

• IBM System/3 Model 15 System Control Programming 
Reference Manual, GC21-5077 

• IBM System/3 Models 4 and 6 Operation Control 
Language and Disk Utility Programs Reference 
Manual, GC21-7516 

• IBM System/3 Model 15 System Control Programming 
Concepts and Reference Manual, GC21-5162 
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How To Use This Publication 



This publication is divided into four chapters: 

1. Sequential Files 

2. Indexed Files 

3. Direct Files 

4. Record Address Files 

Each of the chapters discusses the RPG II specifications needed to create and 
maintain a certain type of file. Since the discussions in each chapter apply to 
a particular file organization, you need read only the chapter for the file 
organization you will use. 

This manual is designed to show you the entries that must be made in order for 
the system to identify the file and determine what functions are to be done. Other 
entries will be needed, but they depend on the job you are doing. Refer to the ref- 
erence manual for your system if you need information on these additional entries. 



Note Concerning Examples 

Most of the examples in this manual use MFCU input files and use 96-column card 
images to represent input records. This does not imply that either the MFCU or 
96-column cards must be used for input; any of several input devices can be used, 
depending on which System/3 model and configuration you have. 

If you are a Model 6 user, you would probably not use a card file for input, al- 
though you may use an online data recorder for card input. Instead, you would 
create sequential disk transaction files in one of the following ways: 

• Using the Keyboard Data Entry conversational utility program (see IBM 
System/3 Model 6 Conversational Utility Programs Reference Manual, SC21 -7528) 

• Using an interactive RPG II, FORTRAN, or BASIC program to build the disk 
file from keyboard input 
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The disk transaction file would then be used to update a disk master file in the 
same way MFCU files are used in the examples in this manual. Thus, the MFCU 
files in the examples could be replaced by sequential disk files. For example: 




Depending on the System/3 model and the I/O devices available, MFCU input files shown 
in most of the examples can be replaced by 80-column card files, console files, tape files, 
5445 disk files, or other types of input files. Models 10, 12, and 15 users can substitute 
DISK45 (5445 disk) or DISK40 (3340 disk) for the device entry DISK (5444 disk) in the 
examples, depending on the equipment they have. Model 6 users should replace the device 
entry PRINTER in the examples with the device entry TRACTR1, and replace Block Length 
and Record Length entries with the beginning and ending print positions. 
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DIRECT ACCESS STORAGE FOR MODELS 12 AND 15 



The IBM 3340 Direct Access Storage Facility attaches to System/3 Model 12, to System/3 
Model 15 (5704-RG1), and to System/3 Model 15 (5704-RG2). 

The IBM 3344 Direct Access Storage Facility also attaches to System/3 Model 15 (5704-RG2). 

Certain areas on the 3340 and 3344 disks are treated as 5444 disks. These areas, known as 
5444 simulation areas, are used for the program libraries and can be also used for certain 
data files. The remainder of the disk space, known as main data area, can only be used for 
data files. 

References in this manual to DISK, DISK40, and DISK45 are to be interpreted according 
to which disk storage device(s) is attached to the system. The following table should be 
used to determine the meaning of the reference: 



Device Type 


Model 15 
(5704-RG1) 


Model 12 or 15 
(5704-RG1) 


Model 15 
(5704-RG2) 


DISK 


5444 Disk 

Storage 

Drive 


5444 simulation 
area on 3340 


5444 simulation 
area on 3340 or 
3344 


DISK40 


Not 
applicable 


Main data area 
on 3340 


Main data area 
on 3340 or 3344 


DISK45 


5445 Disk 
Storage 


Main data area 
on 3340 


Main data area 
on 3340 or 3344 



IBM System/3 5448 Disk Storage Drive 



The IBM System/3 5448 Disk Storage Drive on System/3 Models 8 and 10 uses the same 
program product support as the IBM 5445 Disk Storage. However, a separate system 
control program feature is required for the 5448. In general, references to 5445 in this 
manual also apply to 5448. For specific information about 5448 operating characteristics 
and programming support, see IBM System/3 5448 Disk Storage Drive Program Reference 
Manual, GC21-51S8. 
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Chapter 1. Sequential Files 



A sequential disk file is a group of records arranged in a particular sequence and 
processed consecutively, one after another in the order they occur. 

This chapter explains how to use the RPG 1 1 language to create and maintain a 
sequential file. Sample jobs are used to illustrate these functions. 

To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, you should refer 
to the IBM System/3 RPG II Reference Manual, SC21 -7504 (for Model 10 Disk 
System or Model 1 5), or the IBM System/3 Model 6 RPG II Reference Manual, 
SC21 -751 7, depending on the system you have. 



CREATING A SEQUENTIAL FILE 

To create a sequential file, you make certain entries on the File Description 
■■neet. The f ■■. Mowing entries are required to describe various characteristics of 
the disk file: 



File Description Specifications 




The disk filename must be entered in columns 7 through 14. Column 15 must 
contain an O to indicate the file is an output file. 

All records in a file must be the same length. Thus, column 19 must contain an 
F to specify that the record length is fixed. 

A number that is equal to or a multiple of the disk record length must be 
entered in columns 20 through 23. Hus entry determines the size of the input/ 
output area allocated by RPG II. Fot an explanation on block length calculation, 
see the IBM System/3 Disk Concepts and Planning Guide, GC21 -7571 . if you 
want block length calculated for you by RPG II, assign a block length equal to the 
record length. By blocking disk records you can increase the input/output effi- 
ciency of your program by reducing the number of accesses. You must be sure, 
however, that enough main storage is available for your input/output area. 

Columns 24 through 27 must contain the length of the disk record. Whenever a 
disk file s being described, DISK (Model 6, 10, 15), DISK40 (Model 12 or 15), 
ir DISK45 (Model 10, 1 2, or 1 5) is required in the Device columns. 
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Example of Creating a Sequential File 

Suppose you want to create a customer file on disk. Customer numbers are to be 
assigned on a sequential basis; new customers are assigned the next higher number. 
The file will be used to produce monthly reports of each customer's status. Thus, 
a sequential file will serve your needs. 

To create the sequential file, you must first determine the input record format and 
the output record format (Figure 1 ). The file is created by writing the customer 
data from the input records onto disk. Notice that space is provided on the output 
record so additional information can be added to the record later if necessary. 
Basic information about each customer in the file is also printed in the report shown 
in Figure 2. 

Figure 3 shows the RPG II coding necessary to create the sequential customer file 
and print the report. 
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How to Use This Manual, Note Concerning Examples 
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CREDIT 



bal; 



Output Record 
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= Output code (CM) 
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Figure 1. Input Record and Output Record Formats 



Sequential Files 3 



CUSTOMER 
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13672 8 JONES VARIETY 
301628 JIM'S 5 AND 10 
795246 SCHMIDT HARDWARE 



ADDRESS 



14 S MAIN 

1103 FRANKLIN ST 

600 1ST ST NW 



BEDROCK, TEX 
GLENCOE, MINN 
HILL CITY, MD 



Figure 2. Report of Customer Records 
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On lines 01 and 07, columns 15-17 contain information used 
to sequence check the input record. In columns 1 5 and 1 6, 01 
means that record type 2 must be first followed by record 
type 3 (identified by 02 sequence). The 1 in column 1 7 means 
that one record type 2 and one record type 3 exists. 
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Figure 3 (Part 1 of 2). Creating a Sequential Customer File 
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Figure 3 (Part 2 of 2). Creating a Sequential Customer File 
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MAINTAINING A SEQUENTIAL FILE 

Once a file has been created, it usually needs to be maintained. File maintenance 
means performing those functions that keep a file current for daily processing 
needs. Four common : ile maintenance functions apply to sequential files: 

1. Adding records. 

2. Tagging records for deletion. 

3. Updating records. 

4. Reorganizing a file. 



Adding Records 



After a file is created, you can add records to it. Records can be added to a 
sequential file in either of two ways: 

1. At the end of records in the file. 

2. Between records in the file (creating a new file). 



Adding Records at the End of Records in the File 

To add records at the end of the file, entries are required on the File Descrip- 
tion and Output-Format sheets: 



File Description Specifications 




Some of the entries on the File Description sheet are the same ones needed to 
create a sequential file (see Creating a Sequential File in this chapter). 

Two new disk entries are also needed, one on the File Description sheet and one 
on the Output-Format sheet. These entries are circled. 

An A in column 66 on the File Description sheet tells the system that records 
will be added to the file described on this line. 

The entry on the Output-Format sheet is an ADD in columns 1 6 through 1 8. 
This entry tells the system that the fields defined on the following lines con- 
stitute the record to be added to the file specified in columns 7 through 14. 
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Example of Adding Records to the End of the File 

As you get new customers, you will want to add them to the sequential cus- 
tomer file you created in the Example of Creating a Sequential File. Since 
customer numbers are assigned sequentially, each new customer record can be 
added following the records now in the file. 

The input records and output records will be in the same format as the records 
used to create the file. A report can be printed like the one shown in Figure 4 
to ensure that the new records have been added to the file. 

Figure 5 shows the RPG II coding necessary to add records to the customer file 
and print the report. 
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Figure 4. Report of New Customers Added to the Customer File 
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Merging Records Between Records in the File 

Often records must be added between existing records in a sequential disk file. 
When records must be added in this manner, you must sort the new records and 
re-create the file. This new file contains the added records merged in correct 
order with the records from the original file. 



Example of Merging Records Between Records in the File 

Figure 6 shows the RPG II coding necessary to merge records in the file. This 
example is similar to the Example of Adding Records to the End of the File 
in that the input and output records are the same format and the same report 
is printed. 
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Tagging Records for Deletion 

When a record becomes inactive, you may no longer want to process it with 
the other records. Since the record is not physically removed from the file, 
you must identify the record so it can be bypassed. One way to do this is 
to put a code, called a delete code, in a particular location in the record. 
This code can be any character you want. Any program that should not proc- 
ess deleted records can check for this code. If the code is present, the program 
can bypass the record. The deleted records can be physically removed when 
the file is reorganized (see Reorganizing a File in this section). 



Example of Tagging Records for Deletion 

An example of tagging records for deletion is shown in this section under 
Updating Records, Example of Updating Records. 



Updating Records 

Many jobs require changes to certain data in a record. This function is called 
updating. To update disk files, the following entries are required on the File 
Description sheet: 

File Description Specifications 




Some of the entries are the same entries needed to create a sequential file and 
were discussed in this chapter under Creating a Sequential File. 

The two new entries are circled. Column 1 5 must contain a U to indicate that 
the file is an update file. Column 16 can contain either a P or an S depending 
on whether the file is a primary file or a secondary file. 
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Since updating means getting a record from a disk file, changing some data, 
and putting the record back in its original location, an update file is like a com- 
bination input/output file. For this reason, the file to be updated must be speci- 
fied on both the Input and Output-Format sheets. Field locations should agree 
betweenthe two sheets. Field names may vary depending on the updating being 
done. Field lengths must agree. 
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Example of Updating Records 

Periodically, you might want to update the accounting information for each cus- 
tomer in your customer file. You might also want to tag some customer records 
for deletion. A printed report, like the one shown in Figure 7, lists the updated 
information and the records tagged for deletion. 

The TRANS file contains two input record types. One type identifies disk rec- 
ords to be deleted (D in column 1 ); the other type contains information needed 
to update the MASTER file (3 in column 1 ). Figure 8 shows the RPG 1 1 coding 
necessary to update records and to tag records for deletion. 
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Figure 8 (Part 3 of 4). Updating and Deleting Records in the Sequential Customer File 
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Figure 8 (Part 4 of 4). Updating and Deleting Records in the Sequential Customer File 



Reorganizing a File 



The space reserved for a file often becomes filled as additions are made. Reor- 
ganizing is a means of freeing space by physically removing inactive records 
(those with a delete code) from a file. 

You can reorganize your file using the Disk Copy/Dump program. The DELETE 
or OMIT parameter causes records of a specified type to be deleted from a file 
as it is copied. You can also use the Disk Sort program to remove the records 
tagged for deletion. For information on this program, see the IBM System/3 
Disk Sort Reference Manual, SC21-7522. 
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Example of Reorganizing a File 

Records were tagged for deletion in the Example of Updating Records by placing 
a D in position 1 28. Now suppose you want to reorganize your customer file to 
physically remove these records from the file. You also want to print a report 
listing the customer records deleted (Figure 9). 



To delete these records you want to copy all records that do not have a D in 
position 1 28. Figure 1 shows the RPG 1 1 specifications necessary to reorgani 



the file. 
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DELETED CUSTOMER LIST 



CUSTOMER 
NUMBER 



CUSTOMER 
NAME 



652791 GREEN GROCERY, INC 
5762 9 STAR MARKET 



ADDRESS 



1739-6TH ST SW 
3278 ADAMS ST 



CITY/STATE 

BIG CITY, CALIF 
GOODTOWN, GA 



Figure 9. Report of Deleted Customer Records 
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Figure 10 (Part 1 of 2). Reorganizing the Sequential Customer File to Remove Deleted Records 
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Figure 1 (Part 2 of 2). Reorganizing the Sequential Customer File to Remove Deleted Records 
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Chapter 2. Indexed Files 



An indexed disk file has two parts: an index and the records. The index contains 
the key field and disk address of each record in the file; it is organized sequentially 
by key field. Records in the file are organized in the order in which they are loaded. 
Records in an indexed file can be processed in the following ways: 

1. Sequentially by key. 

2. Sequentially within limits. 

3. Randomly by key or relative record number. 

4. Consecutively (without keys). 

5. By ADDROUTfile. 

This chapter explains how to use the RPG II language to create and maintain a 
single volume indexed file. Sample jobs are used to illustrate these functions. 

To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, you should refer 
to the IBM System/3 RPG II Reference Manual, SC21 -7504 (for the Model 1 
Disk System or the Model 1 5), or the IBM System/3 Model 6 RPG II Reference 
Manual, SC21-7517, depending on the system you have. 

CREATING AN INDEXED FILE 

You can create a single volume indexed file with records that are in ordered or 
unordered sequence. An ordered sequence means the records are arranged in 
order according to the major control field that will be used as the key of the file. 
If an ordered sequence is specified, records are sequence-checked by System/3 
data management. 

An unordered sequence means the records are in no particular order. For example, 
if records in an inventory item file were organized by frequency of use, they would 
be in an unordered sequence with the most active items at the beginning of the file. 
System/3 data management will not sequence check the records or check for dupli- 
cate records while an indexed file is being loaded in unordered sequence. The in- 
dex of an unordered file is sorted into ascending sequence after all the records have 
been loaded. At this time, System/3 data management will detect duplicate records. 



Note: Multivolume indexed files must be loaded in key field sequence, that is, 
in ordered sequence. See Related Publications in the Preface for sources of addi- 
tional information about multivolume files. 
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Creating an Ordered Indexed File 



To create an indexed file in an ordered sequence, you must make the following 
entries on the File Description sheet: 

File Description Specifications 



-f^iK&OKtrodxw 
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block 

Length 
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Sf^SKS****:*::?*: 
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C-.pn ?a t on 
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:0m&&iodi&toc 
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'Sprite 



The disk filename must be entered in columns 7 through 14. Column 15 must 
contain an O to indicate that the file is an output file. 

All records in a file must be the same length, so column 19 must contain an F to 
specify that the record length is fixed. 

A number equal to, or a multiple of, the disk record length must be entered in 
columns 20 through 23. This entry determines the size of the input/output area 
allocated by RPG II. If you want block length calculated for you by RPG II, 
assign a block length equal to the record length. By blocking disk records, you 
can increase the input/output efficiency of your program by reducing the number 
of accesses. You must be sure, however, that enough main storage is available for 
your input/output area. 

Note: Block length calculation and input/output area allocation are described 
in IBM System/3 Disk Concepts and Planning Guide, GC21 -7571 . On Model 1 5, 
RPG II uses double buffering for indexed file output; therefore, main storage 
must be available for at least twice the block length plus twice the index buffer 
length. 

Columns 24 through 27 must contain the length of the disk record. Whenever a 
disk file is being described, DISK (Model 6, 10, 15), DISK40 (Model 12, 15), or 
DISK45 (Model 10, 12, 15) is required in the Device columns. 

Indexed files are allowed only on the main data area, and are not allowed on the 
simulation area. Models with 5445 or 3340 drives must use DISK45 and DISK40 
respectively. 

Entries in columns 31 and 32 indicate that an indexed file is to be created. An I 
in column 32 specifies an indexed file; an A in column 31 specifies that a key 
field exists. 

The other two entries describe the length and location of the key. Key length, 
entered in columns 29 through 30, is the same for all records in a file. The maxi- 
mum key length is 29 characters. The location of the first character of the key is 
specified in columns 35 through 38. Thus, if a 6-character key field were located 
in positions 73 through 78 of a disk record, you would enter a 73 in columns 37 
through 38 of the File Description sheet and a 6 in column 30. 



Indexed Files 27 



Creating an Unordered Indexed File 

To create an indexed file in an unordered sequence, one entry is needed on the 
File Description sheet in addition to the entries needed to create an ordered 
indexed file. This entry is a U in column 66, indicating that the records are to be 
loaded in an unordered sequence: 



File Description Specifications 
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Example of Creating an Indexed File 

Suppose you want to create an inventory file on disk and want to process the rec- 
ords in various ways (sequentially, randomly, within limits). An indexed file pro- 
vides this processing flexibility. Whether you load your records in an ordered or 
an unordered sequence depends on which sequence gives you the most processing 
efficiency. 

To create an indexed file, you must first determine the input record format and 
the output record format (Figure 1 1 ). The file is created by writing the inventory 
item data from the input records onto disk. Notice that the output record format 
provides space so additional information can be added to the record later if nec- 
essary. 

Figure 12 shows the RPG II coding necessary to create the indexed inventory file. 
The program will count the number of records loaded and print the total after the 
file has been created. 
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Note: The input file need not be a card file. See 
How to Use This Manual, Note Concerning Examples 
at the beginning of this manual. 
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Figure 11. Input Record and Output Record Formats 
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Figure 12 (Part 1 of 2). Creating an Indexed Inventory File 
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Figure 12 (Part 2 of 2). Creating an Indexed Inventory File 



MAINTAINING AN INDEXED FILE 



Once a file is created, it usually needs to be maintained. File maintenance means 
performing those functions that keep a file current for daily processing needs. 
Four file maintenance functions apply to indexed files: 

1. Updating records. 

2. Adding records. 

3. Tagging records for deletion. 

4. Reorganizing a file. 
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Updating Records 

Many jobs require you to change certain data in a record. This function is called 
updating. You can update the records in one of three ways: 

1. Sequentially by key. 

2. Randomly by key. 

3. Sequentially within limits. 

Since updating means getting a record from a disk file, changing some data, and 
putting the record back in its original location, an update file is like a combination 
input/output file. For this reason, the file to be updated must be specified on both 
the Input and Output-Format sheets. Field locations should agree between the two 
sheets; field names may vary depending on the updating being done. Field lengths 
must agree. 
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Updating Records Sequentially by Key 

Records are usually updated sequentially by key when you want to update a large 
part of the file. To update records in this way, the following entries are required 
on the File Description sheet: 



File Description Specifications 




jjj^j^^jWi!SiJS::i|l-:; 
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Some of the entries are the same entries needed to create an indexed file and were 
discussed in this chapter under Creating an Indexed File. 

The two new entries are circled. Column 1 5 must contain a U to indicate that the 
file is an update file. Column 16 can contain either a P or an S depending on 
whether the file is a primary or a secondary file. 



Example of Updating Records Sequentially by Key 
For examples of this kind of updating, see: 

• Updating Records, Example of Updating Records in Chapter 1 . This coding 
applies if the necessary File Description sheet entries are made. 

• Adding Records, Example of Adding Records Sequentially by Key later in this 
chapter. 

Updating Records Randomly by Key 

When an indexed file is updated randomly by key, input records are chained to the 
indexed file. Chaining means comparing the record key with the key in the index. 
If the keys are equal, the corresponding data record is made available. The data 
used as a record key in the chain operation can be a field in an input record or it 
can be created in your program. 

Records are read from the indexed file during the calculation phase of the program. 
Fields of records read from chained update files can be read during total calculations 
and updated during total output, or read during detail calculations and updated 
during detail output. Records may also be read during detail calculations from 
chained update files and updated during total output. 

When you update records randomly by key, entries must be made on the File 
Description and Calculation sheets. 
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One new entry is needed on the File Description sheet in addition to the entries 
needed to update a file sequentially by key. One of the previous entries also has 
to be changed. 

File Description Specifications 



xS^tflWrct:; : 



mi" 



Mode of Processing 



Length of Key Field o 



Key Field 
Starting 

Location 
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The changed entry is a C in column 16, which identifies the file as a chained file. 
The new entry is an R in column 28, indicating that the file is processed randomly 
by key. 

The following entries are needed on the Calculation sheet to describe the chain 
operation: 



RPG CALCULATION SPECIFICATIONS 

, - --J-- -. 




Factor 1 must contain the name of the field to be used during the search for a match 
in the index, CHAIN must be entered as the operation, and Factor 2 must contain 
the name of the update file. 



A resulting indicator should be specified in columns 54 and 55 to indicate whether 
the record to be updated is in the index. (If the indicator is omitted, you will get 
an error during compilation.) Refer to the IBM System/3 RPG II Reference 
Manual, SC21-7504 for more information. When a match is found in the index, the 
disk address of the corresponding record is available. The desired record can then 
be located and read into storage. At that time the record can be updated. Your 
program can check to see if the required record is in the file by checking the 
specified resulting indicator. When the indicator is off, the record was found and 
can be updated; when the indicator is on, the record was not found. 
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Example of Updating Records Randomly by Key 

Suppose that whenever a transaction is made you want to update the item record 
in the inventory file. Since the transaction records are not in sequence, you will 
process the file randomly by key. You might also want to tag some records for 
deletion while the file is being processed. 

Figure 13 shows the RPG II coding necessary to update the records and tag records 
for deletion. The TRANS file contains the update and deletion information. 

Refer to Appendix H for more information on blocking records when processing 
an indexed file randomly. 
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Figure 13 (Part 1 of 2). Updating and Deleting Records in the Indexed Inventory File 
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When a record is not found, the input 
card is stacked in stacker 3. If a differ- 
ent input device is used, a different 
method of handling the record-not- 
found condition can be used, such as 
printing a special message or issuing a 
message to the input device. 



The record is tagged for deletion. 



4^- 



Figure 13 (Part 2 of 2). Updating and Deleting Records in the Indexed Inventory File 
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Updating Records Sequentially within Limits 

See Chapter 4 in this manual for information on updating records sequentially 
within limits. 



Adding Records 

After a file is created, it is often necessary to add records to the file. For an 
indexed file, records can be added that contain keys which are: above the highest 
key presently in the file; below the lowest key presently in the file; or in between 
keys presently in the file. In any case, the added records are placed at the end of 
the records presently in the file. The index entry for each added record is written 
at the end of the current entries in the index area. After all records are added, 
the index is automatically sorted by the system. 



If many records are to be added to the file, the time required for the index sort 
can be decreased by allocating a special work file This requires no special RPG II 
coding but does require a special OCL statement. See the section concerning use of 
OCL in the manuals listed in the Preface under OCL References for additional 
information and an example of this option. For a further discussion of indexed 
file performance considerations, see IBM System/3 Disk Concepts and Planning 
Guide, GC21-7571. 

You can add records to a file in one of two ways: 

1. Randomly by key. 

2. Sequentially by key. 



Adding Records Randomly by Key Using Chaining 

Records can be added randomly by key to an indexed file in two ways, either 
with or without chaining. 

Chaining means matching the record key of the record to be added with the 
keys of the index. This matching is done as a check to ensure that the record 
to be added is not a duplicate of a record already in the file. The data used as 
a record key in the chain operation can be either a field in an input record or 
it can be created in your program. 
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When adding records randomly by key using the chaining method, entries 
must be made on the File Description, Calculation, and Output-Format sheets. 



The special File Description entries are shown below: 
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Column 16 must contain a C to indicate the file is a chained file. An R in col- 
umn 28 indicates the file is processed randomly by key. Column 66 contains 
an A, indicating records are added to the file. The File Type entry (column 1 5) 
may be either I or U. The I entry indicates the file will be read, but the file will 
not be updated. The U entry indicates the file will be read and existing records 
will be updated. 

The following entries are needed on the Calculation sheet to describe the chain 
operation: 



RPG CALCULATION SPECIFICATIONS 
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Factor 1 must be the name of the field to be used in the search for a match in the 
index, CHAIN must be entered as the operation, and Factor 2 must contain the 
name of the file. 

A resulting indicator should be specified in columns 54 and 55 to indicate 
whether the record to be added is a duplicate of a record already in the file. The 
record key is used to find the index entry that contains the same key. If a dupli- 
cate is not found, the record can be added to the file. Your program can check 
for duplicates by checking the specified resulting indicator. If the indicator" is 
off, do not add the record because it is a duplicate; if the indicator is on, the rec- 
ord can be added. 
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The entry on the Output-Format sheet is an ADD in columns 1 6 through 1 8: 



RPG OUTPUT FORMAT SPECIFIC 



Pushing j Gra P h 'C 
Punch 




This entry tells the system that the fields defined on the following specification 
lines constitute the record to be added to the file specified in columns 7 through 
14. 



Example of Adding Records Randomly by Key Using Chaining 

Suppose you want to add new inventory items to the indexed inventory file 
created in the Example of Creating an Indexed File. The new records are not 
in sequence. New record keys may be lower, between, or higher than keys 
presently in the file. 

Input and output records will be in the same format as the records used to 
create the file. A printed report (Figure 14) will list all the new records added 
to the file. 




06/18/70 
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412146 CH143 BREAKER 15A 
411126 1500 TWIN SOCKET B 
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Figure 14. Report of New Items Added to the Inventory File 
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Figure 1 5 shows the RPG 1 1 coding necessary to add records to the inventory 
file and print the report. 
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Since a card file is used for input, error records are 
handled by being selected to stacker 3; correct 
records are selected to stacker 1. If another input 
device is used, a different method of handling 
error records can be used, such as printing a 
spiecial message. 



Figure 15 (Part 3 of 3). Adding Records to the Indexed Inventory File 
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Adding Records Randomly by Key Without Chaining 

Chaining is not necessary if no checking is to be done by the program for 
duplicate records and the file is not being read or updated. (The system will 
check for duplicate records and return a halt if duplicates exist, even if chaining 
is not done.) In this method, the indexed file is defined as an output file and 
records to be added are read from a separate file (or generated in the program) 
and written out to the indexed file. The added records are placed at the end of 
the file. After the program has finished, the index is sorted into key field se- 
quence. Records added in this manner may: 

1. Contain keys that are above the highest presently in the file. In this case, 
the records constitute an extension of the file. 



2. 



Contain keys that are either lower than the lowest presently in the file, 
or fall between those already in the file. 



The File Description entries characteristic of this method of adding records to 
an indexed file are: 
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For an example of this kind of add, see Adding Records, Example of Adding 
Records to the End of the File in Chapter 1. The coding used in that example 
applies if the preceding File Description entries are used for the disk file. Use 
06 for length of key field (columns 29 and 30); enter 3 in column 38 for key 
field starting location. 
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Adding Records Sequentially by Key 

Records added to an indexed file sequentially by key (either single volume 
or multiple volumes) must either: 



1. Be added between existing records (that is, the key of the record being added 
must be lowei than the last key retrieved and higher than the preceding key) 
or 

2. Have keys that are hiuher than existing keys in the file (that is, the indexed 
file is at end of file). 

The unshaded columns on the File Description and Output-Format sheets below 
indicate entries that must be made to add records sequentially by key. Some of 
the File Description entries are also used to create an indexed file; these entries 
are discussed under Creating an Indexed File, previously in this chapter. 



File Description Specifications 




File Addition/Unordered 
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The File Type entry (column 15) can contain either an I or a U. The I entry indi- 
cates that the file will be read, records will be added, but no updating will be done. 
The U eiur„ indicates that records will be read and updated and new records will 
be adfiec. 

Two special entries are needed lo add records, one on the File Description sheet 
and one on the Output- Format sheet. These entries are circled. 

The entry on the File Description sheet is an A in column 66. This entry tells the 
system that records will be added to the file described on this line. 
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The entry on the Output-Format sheet is an ADD in columns 16 through 18. This 
entry tells the system that the fields defined on the following lines constitute the 
records to be added to the file specified in columns 7 through 14. 

Records might be added sequentially to an indexed file in situations where the 
activity of the file is high and the records to be added have been previously sorted 
into ascending sequence by key field. Adding sequentially in this kind of situation 
can result in better performance than adding records randomly with chaining by 
allowing large blocking factors. 



Example of Adding Records Sequentially by Key 

Suppose you want to add new inventory items to the indexed inventory file 
created in Example of Creating an Indexed File, previously in this chapter. The 
new item records are merged with records of receipts of existing items; thus, 
existing inventory records are updated and new records are added during the 
same program run. The activity of the inventory file (number of transactions 
against the file) is high, so the transaction file, containing new items and receipts, 
is organized into ascending sequence by item number (key field), enabling the file 
to be processed sequentially by key. Input records for new items are in the same 
format as the inventory records. 

Figure 1 6 shows the coding to update the inventory file and to add new item rec- 
ords to the file. At the same time, a list of new inventory items is printed, similar 
to the list produced in the example of adding records randomly to the inventory 
file (Figure 13). 
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Figure 16 (Part 2 of 4) Adding Records Sequentially by Key 
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Tagging Records for Deletion 

When a record becomes inactive, you probably will not want to process it with the 
other records. Since the record might not be physically removed from the file, how- 
ever, you must identify it so it can be bypassed. One way to identify the record is 
to put a code, called a delete code, in a particular location in the record. This code 
can be any character you want. Any program which should not process deleted 
records can check for this code. If the code is present, the program bypasses the 
record. The deleted records can be physically removed from the file by reorganiz- 
ing the file (see Reorganizing a File in this section). 



Example of Tagging Records for Deletion 

An example of tagging records for deletion is shown in this section under Updating 
Records, Example of Updating Records Randomly by Key. 



Reorganizing a File 

Reorganizing a file is similar to creating the file. Reorganization may be necessary 
for two reasons: 

1. To increase processing efficiency. 

2. To free disk space. 

You can increase processing efficiency by restoring your file to its original sequence. 
When you add records to a file, these records are added at the end of the records 
already in the file; however, the keys are always in order in the index. When the file 
is processed sequentially by key, the disk access arm moves back and forth between 
the sequenced records (those originally created) and the added records. This increases 
processing time. 

Disk space can be made available by removing inactive records during a file copy. 
All records with a delete code can be physically deleted from the file. 

If you want your file in an ordered sequence, you can reorganize the file to place 
the added records in sequence with the records originally created and remove rec- 
ords tagged for deletion. To reorganize the file in this manner, you can use the IBM 
Disk Copy/Dump program. For an explanation on how to use this program, see the 
IBM System/3 Model 10 Disk System Control Programming Reference Manual, 
GC21 -751 2, the IBM System/3 Model 15 System Control Programming Reference 
Manual, GC21 -5077, or the IBM System/3 Model 6 Operation Control Language 
and Disk Utility Programs Reference Manual, GC21 -7516, depending on the system 
you have. 

If you want your file in an unordered sequence and want only to delete records in 
the file, you can also use the IBM Disk Copy/Dump program. 

When you want to change the order of the records and maintain an unordered se- 
quence, you must determine what method can be used to produce the file in the 
required order. For example, if a count of activity was maintained in each master 
record, the file could be sorted in descending sequence on this activity field, then 
reloaded as an indexed file. This would place the most active records at the front 
of the file. 
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OTHER WAYS TO PROCESS INDEXED FILES 



Processing an Indexed File Consecutively 

An indexed file may be processed consecutively (read only) by defining the indexed 
file as a sequential input file in the File Description Specifications. When an indexed 
file is processed consecutively, the file index is bypassed and data records are read 
consecutively from the beginning of the file to the end, exactly as a sequential file. 
Indexed files may not be created, added to, or updated consecutively. 

Consecutive processing of an indexed file is useful, for example, for reading records 
from an indexed file when the file index is unusable for some reason. 



Processing an Indexed File Randomly by Relative Record Number 

An indexed file may be processed randomly by relative record number if the file 
is an input file. The file must be described as a sequential file (that is, columns 31 
and 32 must be blank) and must be described as a chained file (C in column 16 of 
the File Description sheet). The CHAIN operation code must be used in calcula- 
tions to read records from the file. Records may not be updated, added, or written 
out to an indexed file using this method. 

Random processing of an indexed file by relative record number can provide im- 
proved performance over random processing by key, because the file index need not 
be read. However, it is the user's responsibility to ensure that records in the indexed 
file are properly sequenced for this type of processing. 
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Chapter 3. Direct Files 



A direct file is one in which records are assigned specific record locations on disk. 
Direct file organization enables the program to access any record in the tile with- 
out examining other records or searching an index. 

This chapter explains how to use the RPG II language to create and maintain a 
direct file and to retrieve records from the file. Sample jobs illustrate these func 
tions. 

To understand the sample jobs, a basic knowledge of RPG II is necessary. If you 
do not fully recall some of the coding used in the sample jobs, refer to the IBM 
System/3 RPG II Reference Manual, SC21-7504 (for the Model 10 Disk System 
or the Model 1 5), or the IBM System/3 Model 6 RPG I! Reference Manual, 
SC21 -751 7, depending on the system you have. 



CREATING A DIRECT FILE 

To create a direct file, you must define a disk file as a chained output file. The 
following entries are needed on the File Description sheet to describe various 
characteristics of the disk file: 
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File Description Specifications 
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The disk filename must be entered in columns 7 through 14; column 15 must con- 
tain an 0, and column 16 a C, indicating that the file is a chained output file. 

All records in the file must be the same length. Thus, column 19 must contain 
an F to specify that the record length is fixed. 

A number equal to or a multiple of the disk record length must be entered in 
columns 20 through 23. This entry determines the size of the input/output area 
allocated by RPG II. For an explanation on block length calculation, see the 
IBM System/3 Disk Concepts and Planning Guide, GC21 757 1 . If you want 
block length calculated for you by RPG II, assign a block length equal to the rec- 
ord length. By blocking disk records you can increase the input/output efficiency 
of your program by reducing the number of accesses. You must be sure, however, 
that enough main storage is available for your input/output area. 
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Columns 24 through 27 must contain the length of the disk record. Column 28 
contains an R to indicate that random processing is to take place. Whenever a disk 
file is being described, DISK (Model 6, 10, 15), DISK40 (Model 12 or 15), or DISK45 
(Model 1 0, 1 2, or 1 5) is required in columns 40 through 46. 

Relative record numbers are always used with the CHAIN operation code in your 
program to make the corresponding record locations in a direct file available for 
loading. The data used as a relative record number in the chain operation can be 
either a field in an input record or it can be created in your program. To use the 
chain operation, you must make the following entries on the Calculation sheet: 
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Factor 1 must contain either the name of the field containing the relative record 
number or the relative record number itself. CHAIN must be entered as the opera- 
tion, and Factor 2 must contain the name of the file to be loaded. 

A resulting indicator should be specified in columns 54 and 55 with the CHAIN 
operation. If the record is not found (that is, the record location does not exist in 
the file) the indicator specified in columns 54 and 55 is turned on. This situation 
can occur either when the relative record number is higher than the highest record 
location in the file or when the relative record number is invalid for some other 
reason. If an indicator is not specified in columns 54 and 55 and the record is not 
found, the program halts. 



When a direct file is loaded as a chained output file, disk system management 
clears the entire file area to blanks before records are loaded. Thus, if a record is 
not loaded, the space reserved for it remains blank. Programs written to access 
records in the direct file should check each record for blanks before attempting to 
process it, since the record may not have been previously loaded. 

The method you use to write data records on the file depends on whether you must 
check for synonyms among those records. Synonyms are two or more records whose 
control fields yield the same relative record number. For more information on syn- 
onyms, see the IBM System/3 Disk Concepts and Planning Guide, GC21 -7571 . 



Creating a Direct File without Synonyms 

A direct file can be created without synonyms when the relative record number 
either corresponds to a field containing sequential values or is derived in such a way 
that no synonyms are produced. 

When you do not have synonyms, you can load records into a direct file in a single 
pass. You do this by specifying a chained output file and writing records in the file 
by means of the chain operation. Record locations cannot be inspected before they 
are filled with data. If a synonym is encountered, it is written over the previous 
record. The previous record is lost. 



Example of Creating a Direct File without Synonyms 

Suppose you want to create a customer file on disk. The following are significant 
characteristics of the file: 



• Customer numbers are assigned on a sequential basis; new customers are 
assigned the next higher number. 

• Deletions from the file are few. 

• The file will be used to process invoices, orders, and cash payments in a random 
manner. 

• The file must allow direct inquiry to any customer's record. 



• 



The file has low activity; for example, out of 5000 customer records, only 100 
invoices are processed per day. 



You need both the direct and consecutive processing capabilities offered by indexed 
and direct file organizations. Because the customer numbers are assigned consecu- 
tively, synonym records are not a consideration. For this reason, and because there 
will be few deletions from the file creating wasted space, direct file organization 
provides maximum flexibility and access speed. 

Your first step, then, is to create the direct file. The record format shown in Figure 
16 satisfies your information needs. Additional fields in the record will contain 
information to be used in specific jobs, such as customer payments, invoicing, and 
sales analysis. (Various applications using the customer file are described later in 
this chapter.) 

The file is created from data on input records (Figure 17). The customer number 
(CUSTNO) is used as the relative record number to chain to the direct file. The 
customer data from the input records is then written on disk. Each record written 
on disk is also printed in the report shown in Figure 18. 

Figure 19 shows the RPG II coding necessary to create the direct customer file. 
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Figure 18. Report of Customer Records 
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Figure 19 (Part 2 of 2). Creating a Direct Customer File 
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Creating a Direct File with Synonyms 

If you have synonyms, you can create a direct file by using more than one job to 
load records into the file. The exact method you use depends on how you plan to 
handle synonym records. Your first job must define the disk file as a direct output 
file, causing disk system management to clear it to blanks. Since blank record 
locations indicate an unused location, clearing the file to blanks is necessary to en- 
sure that no unwanted characters are left in the file area. Once the file has been 
cleared, one or more subsequent jobs can be run using the update function to read 
record locations and check for synonyms while loading the file. 

Figure 20 shows a method of defining a direct file and clearing it to blanks. In 
this method, the input record file from which the direct file is created is placed in 
the MFCU; another type of input, such as a sequential disk file, could be used. 
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Figure 20 (Part 1 of 2). Defining a Direct File and Loading Only the First Record 
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Figure 20 (Part 2 of 2). Defining a Direct File and Loading Only the First Record 



The disk file, which is specified as a chained output file, is cleared to blanks by disk 
system management after the job begins. The CHANUM field from the input file is 
used to chain to the corresponding location in the direct file, and the first record is 
placed in the file. The last record (LR) indicator is then turned on by a SETON 
operation, forcing the end-of-job condition. The direct file now contains a single 
record. This job can be immediately followed by one or more jobs which read the 
remaining records from the MFCU and write out the disk records, using the update 
function. 

After your direct file is defined and cleared to blanks, different steps are required 
to put records into the file, depending on the method you use to handle synonyms. 
There are several ways to handle synonyms. Two of the most common methods 
are: 

1. Storing all synonyms in an area of the file set aside for them. 

2. Storing synonyms in unused record locations between the records in the file. 
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If the first method is used, all records can be placed in the direct file in a single job. 
That job would retrieve and check each record location before it is filled. If the 
location already contains a record (that is, the record to be written is a synonym), 
the synonym is stored in the next available location in the part of the file set aside 
for synonyms. Thus, all home records and synonyms are placed in the file in a 
single job. A home record is the first synonym record; it is stored in the record 
location indicated by its relative record number. The rest of the synonyms are then 
linked together so they can all be found by locating the home record. For more 
information, see the IBM System/3 Disk Concepts and Planning Guide, GC21 -7571 . 

If the second method is used, two jobs are required to place home records and syn- 
onyms in the direct file. The first job loads all home records; synonyms are by- 
passed. The second job loads synonyms in the record locations available between 
home records. Both jobs are done using the update function to check each record 
location. 

Whatever method you use to handle synonym records, you will have to devise a 
sequence of jobs similar to those just described. Remember: 

1. You load a disk file as a direct file by specifying a chained output file. 

2. In order to check for synonyms, you must use the update function. Random 
update with a direct file is described later in this chapter. 



RETRIEVAL OF RECORDS IN A DIRECT FILE 

Record retrieval is used when you want to get information from a record, but do 
not want to modify the record. You would normally use this method when you 
want to get data from a record to produce a report. Record retrieval can be done 
either consecutively, randomly by relative record number, or randomly by 
ADDROUT file. For a discussion of record retrieval done randomly by ADDROUT 
file, see Chapter 4 in this manual. 
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Consecutive Retrieval 

Consecutive retrieval of records from a direct file requires the following entries on 
the File Description sheet: 



File Description Specifications 




Some of these entries are the same ones needed to create a direct file and were dis- 
cussed in this chapter under Creating a Direct File. 

The new entries are circled. An I is entered in column 1 5 to indicate that the file 
is an input file. Column 16 can contain either a P or an S depending on whether 
the file is a primary or secondary file. Because the file is an input file, it must also 
be defined on the Input sheet. 
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Example of Consecutive Retrieval 

Suppose you want to process the direct customer file, CUSTFILE, created in the 
Example of Creating a Direct File without Synonyms, to produce a monthly report. 
This report lists all customers that have had no sales activity during the period. This 
report is analyzed by sales personnel, who then make follow-up calls. Since all the 
customer records will be checked and since the file is in sequence by customer num- 
ber, the report is produced by consecutive processing of the direct file. 

The format of the disk records in CUSTFILE is shown in Figure 21. Figure 22 
shows a part of the report produced by the consecutive processing job. The report 
consists of fields selected from CUSTFI LE and an accumulated total for accounts 
receivable (TOTAR). 

Figure 23 shows the specification sheets necessary to consecutively retrieve records 
from CUSTFI LE to produce REPORT1 , which is a list of recently inactive customers. 

Since the direct file probably contains blank record locations and inactive records, 
a technique is employed on the Input sheet to bypass such records (Figure 23). If 
a method is not used to bypass unidentified records, the program halts when they 
are encountered. 
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Figure 21. Disk Record Format for the Direct Customer File 
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LSTORD = Last order date 

LSTPAY = Last pay date 

THSPER = Charges for this period (month) 
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Figure 2Z Report of Inactive Customers in the Direct Customer File 
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Figure 23 (Part 1 of 2). Consecutive Retrieval of Inactive Customers in the Direct Customer File 
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Figure 23 (Part 2 of 2). Consecutive Retrieval of Inactive Customers in the Direct Customer File 
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Random Retrieval 

Random retrieval of records from a direct file requires the following entries on the 
File Description sheet: 



File Description Specifications 
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Some of these entries are the same ones needed to create a direct file and were dis- 
cussed in this chapter under Creating a Direct File. 

The circled entry, an I in column 15, is new. This entry indicates the file is an input 
file. 

The records in the direct file to be retrieved must be further described on input 
specifications. On the Input sheet, a direct file being retrieved must have an alpha- 
betic sequence entry (columns 15-16), because sequence checking cannot be done 
for chained files. 

If the direct file being retrieved contains synonym records, calculations must be 
included in the program to test for synonyms and retrieve the desired record. The 
CHAIN operation code must be specified on the Calculation sheet to randomly 
retrieve records from a direct file. The entries on this sheet are the same ones dis- 
cussed in this chapter under Creating a Direct File: 
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Example of Random Retrieval 

Suppose the direct customer file, CUSTFILE, created in the Example of Creating 
a Direct File without Synonyms and processed consecutively in the Example of 
Consecutive Retrieval, is to be retrieved randomly. You want to make demand 
inquiries each day concerning customer sales and account information. Inquiries 
are received for records containing an I in column 1 followed by the customer 
number of the record to be retrieved (Figure 24). Inquiry records are read from 
the primary MFCU hopper in this example; substitute devices such as console/ 
keyboard devices, can also be used. When an inquiry record is read, the customer 
number (CSTMER) is used as the relative record number to chain to CUSTFILE. 

The format of the disk records in CUSTFI LE is the same as the disk record format 
used in the consecutive retrieval example. 

If a record that corresponds to the number on the inquiry record is found in 
CUSTFILE, a response is printed in the format shown in Figure 25. This response 
lists pertinent sales information and the total accounts receivable amount. 

The RPG II coding for the random inquiry application is shown in Figure 26. 



Record ID Code 




Figure 24. Inquiry Record Format 



' : ' 1 1 1 [ ■ 

2 J : 4-5J6|7!8.9io 



Tffi 



70) 



LCU$fM) 



2 5;4:5 6 1 r j a ;9 






(AC.Copei 



in\l 2 22 2 2 2 1 

' |2j3;4 5l6.7 8 9 



#?AD:/J TMsLWjM ..UtS£ P&; , Sl^j!Mli££fL.^JJ,Msr. P£K\ TomLW^ 



( S.L.SHHfJ. . 



?'Vi : V5 J 3 J } A 
i 2 3456,7890 



?! J 4 5|6i? 8 90 






M >uk-n\ 



jXJHsre/t..) ^^-Jksjre&x . ..(jonK). 



~ 'MLut-M^^MiX* 



CUSTOMER ACTIVITY SALESMAN CREDIT LAST ORDER LAST PAY SLS THIS PER SLS LAST PER TOTAL A/R 

3119 A 105 01 4/17/71 4/01/71 360.00 239.50 360.00 

6678 RECORD NOT FOUND-- INVALID RECORD NUMBER 

1703 I 35 03 11/19/70 12/01/70 .00 .00 00 



Figure 25. Printer Output from Random Inquiry Requests 



Direct Files 67 



IBM 



RPG CONTROL CARD AND FILE DESCRIPTION SPECIFICATIONS 



Program _ 
Programm 



Punch 



-4 



75 76 77 78 79 1 

,on LJ L. 1 L L 



Control Card Specifications 




Refer to the specific System Reference Lihr.ir 



i 57 t.8 59 60 61 62 6:i G4 65 fi(i (>7 68 f 



Symbolic 
Device 



Name of 
Label Exit 



Extent Exit 
for DAM 



The direct file is defined 
as a chained input file to | 
be retrieved randomly. 



File Aclclition/Um 



Number of Tr;>ck 
for Cylinder Over 



il 



IBM 



RPG INPUT SPECIFICATIONS 



,,;,.■,' ~i 



i _. L 



M 



-fit''! :tj 



TffXUS. 



ZfJlST FILERS 



H$ 



w 



Hecoid Identification Code; 



A chained file must contain 
an alphabetic sequence entry. 



antain I 
:e entry. I 



1 

4 

7b 
22 



t, 

12 
47 

S3 
95 



CSTM£$ 



ACCODE 
CUSTNO 
SLSM/14 
CREDIT 
LSTORJ) 
LSTPftl 

THSpeR 
L$TP£% 



02 



Figure 26 (Part 1 of 2). Random Retrieval of Inquiry Requests on the Direct Customer File 
68 



IBM 



Programmer 



RPG CALCULATION SPECIFICATIONS 

:.q Tip:: 



Form X21-9093 



75 ?G 77 78 79 80 



Graph k 
1 Punch 



>-m :zz^[J J] ]j 



5 

-j ..- 
' 6 

4: 

:8 



<Z>1 



IS 

15 

WW13 



3 Yl 3 



'iff »$ *3 so ?< y? ?-> y< y y* ?•> 



^CZTWEK 



TO TAR 






. A 



Operation 



?° v v* •*< r> 



CHA.I H 



MM6.& 



TOTfiR . . ]fiPJ>. fiRO V90. . TQTAR 



cos 



1 w w 41 «1 






<j/?306<Z> 



Indicator 13 is used to condition 
subsequent operations. 



] 



r- 



■v-i *a **. **, <& & 



TO 



&& 



TOTAf 

tota 



t+t r-H r + 



Field 
Length 



21 



Plus, Minus) Jero 



<igh 'Low I Eq„ai 
>2i 1< 2 1 ? 



r ..r. ■ ■ ,:■■:- ; 

-4^ _! 



13 

j 

■ • 

-h 



61 6? i)3 64 6h 66 6/ 



The customer number from the 
input record is used as the 
relative record number to chain 
to the direct file. Indicator 13 
will turn on if 3 record is not 
lound in the direct file. 



I 



IBM 



RPG OUTPUT SPECIFICATIONS 

- i- r">«" i. j_I .. .7Ll 



,-. I i i - /■> 



OR 



m 



Output Indicators 



Pf 



IM13 means that this line 
will be printed if a record 
is found in the direct file. 



1*7 



*>Vtf3 



i'3 



When a record is not found in the 
direct file, this line is printed. 



JZ> 



»7 



ZL u Ot 59 Hi) /9 99 <i9 f) CS 19 iy 09 69 89 / S 99 QS P9 £S £4 19 09 



CUSTflO 
QCCQl>£ 



kl/1 3 



1 * 


cttu Nurrl 










"> '' <■-■ 




;,";;'• 



7Fi /e ,'/ 78 75) 80 



No Sniri CR 






^ 
# 



■CUSfOMEji' 
'ACTjyjTy 

'S/)L£\5MAH ' 



u 



(Other fields — see printed report 



J 






V (Other headings — see printed report) I 



CSTMBA 



91 



'fECpfP f:im&££\ ' I j L. 



'fq 'fiJCp^ |//V] 'f\. 



'fc 



VOe 



' iv iv op <m: Hi: r<: 9£ 9s; vi: cs: ;t: is: oc 6^ B£ K. !)<• 'i^ tv. tv a \i or. t 



t"""| ' ' 
I I , . 



Figure 26 (Part 2 of 2). Random Retrieval of Inquiry Requests on the Direct Customer Fil 



Direct Files 69 



MAINTAINING A DIRECT FILE 

After a file is created, file maintenance is usually necessary to keep the file current. 
Three file maintenance functions apply to direct files: 

1. Adding records. 

2. Tagging records for deletion. 

3. Updating records. 

Adding Records 

Unlike sequential and indexed files, direct files can have space available between 
records for new records to be added. Records are added to a direct file by a nor- 
mal update operation (either consecutive or random processing) as follows: 

1. The relative record number is developed for the record to be added. 

2. The location is read into main storage. 

3. If the location is blank, the new record can be stored. 

4. If the location is occupied, and the program can handle synonyms, the new 
record can be stored as a synonym. 

For a discussion of the entries needed to add records consecutively, see Updating 
Records, Consecutive Updating of Records in this chapter. For a discussion of 
the entries needed to add records randomly, see Updating Records, Random Up- 
dating of Records in this chapter. 

If records must be added but the allotted file space is full, you must increase the 
total space available for the file. The Disk Copy/Dump program can be used to 
copy the file into a larger area. For an explanation on how to use this program 
to copy the file, see the IBM System/3 Model 10 Disk System Control Program- 
ming Reference Manual, GC21 -751 2, the IBM System/3 Model 15 System Con- 
trol Programming Reference Manual, GC21 -5077, or the IBM System/3 Model 6 
Operation Control Language and Disk Utility Programs Reference Manual, 
GC21-7516, depending on the system you have. 



Tagging Records for Deletion 

Like sequential and indexed file records, direct file records can be identified for 
deletion by a delete code. This code is usually a single character at a particular 
location in the record. When the file is processed, your program must check for 
the delete code; if the code is present, the record can be bypassed. 

Since the record has a delete code, the record location is available for a new 
record. Either a synonym for a different location can be stored there, or the 
location can be reused by assigning the relative record number to a new record. 
If the file contains synonyms, be careful not to delete synonym linkage inform- 
ation when you delete a record and reuse the location. 



70 



Another method of deleting records, which may sometimes be preferable to 
using a delete code, is to restore the record location to blanks. A blank record 
in a direct file is an available record. 

You cannot delete records from a direct file by using the Disk Copy/Dump pro- 
gram. Because the DELETE parameter of the COPYFI LE control statement 
causes physical deletion of identified records, the DELETE parameter would 
destroy the relative positions on which direct file organization depends. 



Example of Tagging Records for Deletion 

You tag direct file records for deletion in the same way as sequential or indexed 
file records. For an example of this method, see the examples of tagging records 
for deletion in Chapters 1 and 2. 



Updating Records 

To modify certain data in the disk records, you must use the update function. 
Updating means getting a record from a disk file, changing some data, and putting 
the record back in its original location. Thus, an update file is like a combination 
input/output file. 

The file to be updated must be specified on both the Input and Output-Format 
sheets. Field locations should agree between the two sheets. Field names may 
vary depending on the updating being done. Field lengths must agree. 
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Consecutive Updating of Records 

If all or most of the records in a direct file are to be processed, you may want to 
update the file consecutively. Consecutive updating of records in a direct file 
requires the same File Description entries as consecutive retrieval of a record, with 
one exception: column 15 must contain a U to indicate that the file is an update 
file: 

File Description Specifications 




Example of Consecutive Updating 

Suppose the direct customer file created in the Example of Creating a Direct File 
without Synonyms and retrieved consecutively in the Example of Consecutive 
Retrieval is to be updated. At the end of each sales period, when all reports are 
completed, the sales figures for that period must be adjusted. Sales amounts for 
the last period (LSTPER, Figure 21) are replaced by sales amounts from the cur- 
rent period (THSPER). The field containing the current sales amount is reset to 
zero, ready to accumulate the sales amount for the next selling period. Fields 
containing overdue amounts will be updated when the monthly accounts receiv- 
able statements are written. 

Figure 27 shows the coding necessary to consecutively update CUSTFILE. As 
an update file, CUSTFILE must be defined by file description specifications, 
and the fields to be updated must be described by input and output specifica- 
tions. Customer records are read, updated, and written out in the order they 
are stored in the direct file. 
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Figure 27 (Part 1 of 2). Consecutive Updating of Records in the Direct Customer File 
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Figure 27 (Part 2 of 2). Consecutive Updating of Records in the Direct Customer File 
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Random Updating of Records 

Random updating of records in a direct file requires the same File Description 
entries as random retrieval of a record, with one exception: column 1 5 must con- 
tain a U to indicate that the file is an update file: 
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If the direct file being updated contains synonym records, calculations must be 
included in the program to test for synonyms and locate the desired record. 
Thus, the CHAIN operation code must be specified on the Calculation sheet. 
The entries on the sheet are the same ones discussed in this chapter under Creating 
a Direct File: 
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Example of Random Updating 

Each day you want to prepare invoices for customer orders for the file described 
in the Example of Consecutive Retrieval. Information from the invoices is used to 
update the customer file, CUSTFI LE. Since this information is read from records 
(Figure 28) in an unordered manner, a random update job is required. 

The input records contain the date and total amount of the transactions for each 
customer. New addresses are also on this record when required. As each record 
is read, the customer number (CUSTMR) is used to chain to the direct file. The 
amount of the transaction is added to total sales for the period (THSPER) and to 
the accounts receivable amount (ARLT30). The transaction date is placed in the 
date of last order field (LSTORD) in the customer record. 

If an address change is indicated (an X in column 1 8 of the input record), the new 
customer address replaces the old. If a record is not found in CUSTFI LE because 
of an invalid relative record number, the input record is printed, followed by the 
statement "Above record not found— invalid customer number." 

CUSTFI LE, described as a chained update file, must be described on both Input 
and Output-Format sheets because data is read from and written on the file. The 
specifications are shown in Figure 29. 
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Figure 29 (Part 1 of 2). Random Updating of Records in the Direct Customer File 
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Figure 29 (Part 2 of 2). Random Updating of Records in the Direct Customer File 
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Chapter 4. Record Address Files 



Record address files are input files that indicate (1 ) which records are to be read 
from disk files and (2) the order in which the records are to be read from the disk 
tile. There are two types of record address files: 

1. Files containing relative record numbers. 

2. Files containing record key limits. 

This chapter explains how to use the RPG II language to process these two types 
of record address files. Sample jobs are used to illustrate the functions. 

To understand the sample jobs, a basic knowledge of RPG 1 1 is necessary If you 
do not fully recall some of the coding used in the sample jobs, you should refer 
to the IBM System/3 RPG II Reference Manual, SC21 -7504 (for Model 1 Disk 
System or the Model 1 5), or the IBM System/3 Model 6 RPG II Reference Man- 
ual, SC21 -751 7, depending on the system you are using. 

FILES CONTAINING RELATIVE RECORD NUMBERS (ADDROUT FILES) 

A record address file that contains relative record numbers is called an ADDROUT 
file. ADDROUT files are comprised of 3-byte, binary, relative-record numbers 
that indicate the relative position (first, twentieth, ninety-ninth, etc.) of records 
in the file to be processed. 

An ADDROUT file can only be a disk file. All types of file organization (sequen- 
tial, indexed, or direct) for primary or secondary files can be processed by an 
ADDROUT file. When an RPG II program uses an ADDROUT file to process a 
file, it reads a relative record number from the ADDROUT file, then locates and 
reads the record situated at that relative position in the file being processed. Only 
records with relative record numbers in the ADDROUT file are processed. 

Creating an ADDROUT File 

An ADDROUT file is created by the Disk Sort program. For an explanation on 
how to create an ADDROUT file, see the IBM System/3 Disk Sort Reference 
Manual, SC21-7522. 
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Processing by an ADDROUT File 

To use an ADDROUT file to process a file in an RPG II program, entries must be 
made on the File Description and Extension sheets. Input specifications are not 
required. 



File Description Specifications 

The File Description sheet must describe both the file to be processed and the 
ADDROUT file. The description of the file to be processed must contain the 
following entries in addition to the usual entries necessary to describe the file: 
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File Description Specifications 
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Column 28 must contain an R to indicate that the file is to be processed randomly. 
Column 31 must contain an I to indicate that the file is to be processed by relative 
record numbers from an ADDROUT file. 

The ADDROUT file must be described with the following entries: 

File Description Specifications 




The ADDROUT filename must be entered in columns 7 through 14. Column 15 
must contain an I to indicate that the file is an input file. Columns 1 6, 31 , and 
32 contain an R, I, and T respectively; these three columns indicate that the file 
is a record address file consisting of relative record numbers. 

Because all records in a file must be the same length, column 19 contains an F to 
indicate that the record length is fixed. 
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The record length (columns 24 through 27) and the length of the record address 
field (columns 29 through 30) are always 3 because the ADDROUT file consists 
of 3-byte, relative record numbers. The block length should be equal to or a 
multiple of the record length. 

Whenever a disk file is described, DISK (Model 6, 10, 15), DISK40 (Model 12 or 15), 
or DISK45 (Model 10, 12, or 15) is required in the Device columns. Since the file must 
be further defined on the Extension sheet, column 39 must contain an E. 



Extension Specifications 

Two entries are needed on the Extension sheet if you want to process by an 
ADDROUT file: 
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Columns 1 1 through 1 8 must contain the name of the record address file. This 
name must be the same one given to the record address file on the File Descrip- 
tion sheet. 

Columns 19 through 26 must contain the name of the file to be processed. This 
name must be the same filename defined on the File Description sheet. This 
entry indicates that the file is to be processed by the ADDROUT file coded in 
columns 11 throuoh 18. 



Example of Processing by an ADDROUT File 

You have a custome' master file containing: 

• Customer numbers and addresses 

• Salesman numbers 

• Accounts receivable amounts 

The file is an indexed file processed by customer number. It is processed through- 
out the month for invoicing and at the end of every month for customer statements. 
Along with the monthly statements, the sales department wants the accounts receiv- 
able, printed by customer number within salesman number, for all customers owing 
more than $2500.00. 
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In order to do this, the records of customers who owe more than $2500.00 must 
be sorted according to salesman number. You sort the file using an ADDROUT 
sort because there is not enough disk storage to use a tag-along sort. After the 
file is sorted, you have an ADDROUT file of records to be printed. The output 
of the sort becomes input to an RPG II program. Figure 30 shows the RPG II 
entries required to use the ADDROUT file as input to an RPG II program. 
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Figure 30. Processing by an ADDROUT File 
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FILES CONTAINING RECORD KEY LIMITS 

A record address file with record key limits contains the lowest and the highest 
key fields for a specified section of an indexed file. Record address files contain- 
ing record key limits can be entered from disk, card, or a printer-keyboard. They 
are used to process only indexed files. When a section of an indexed file is pro- 
cessed using record key limits, the processing method is known as sequential 
within limits. 



Creating a File with Record Key Limits 

The following rules must be observed when you create a record address file with 
record key limits: 

• Only one record address file can be used for each RPG II program, but the 
record address file can contain several sets of limits. 

• Only one set of limits is allowed on each record in a record address file. 
Since a set of limits is comprised of two keys, the length of each record in a 
record address file is twice as long as the length of the record key. 

• The low record key must begin in position 1 of the record. 

• The high record key must immediately follow the low record key. No spaces 

are allowed between the two keys. If the key field were four bytes long and 

the low record key were 2000 and the high record key 3000, the record would 

look like this: 

/ 

20003000 



Each record key can be from 1 through 29 characters long. 
An alphameric record key can contain blanks. 



• 



The length of the keys must equal the length of the key field in the indexed 
file. To make the length of the keys equal, leading zeros may have to be 
placed in a numeric record key or blanks in an alphameric record key. For 
example, if the low record key were three positions (200), the high record 
key four positions (2999), and the length of the key field in the indexed file 
four positions, a zero must be placed before the 200 to make it a 4-position 
number. The record would look like this: 



/ 02002999~ 



Each key length must also equal the key field length you specify in columns 
29 and 30 of the File Description sheet. 

The same set of limits can appear on more than one record in a record address 
file. Therefore, records within a set of limits can be processed as many times 
as needed. 

• The two record keys in a set of limits can be identical. For example, both the 
low and high record keys can be 2999. In this case, only one record (2999) 
will be processed. 



• 
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Processing Sequentially within Limits 

Processing a section of an indexed file sequentially by record keys is known as 
sequential within limits processing. The RPG II program uses one set of limits 
(one record in a record address file) at a time. Records are read from the section 
of the indexed file specified by the limits. When the records specified by one set 
of limits have been read, the program reads another set of limits from the record 
address file. The program continues reading records in this manner until the end 
of the record address file is reached. 

To process a file by a record address file using RPG II, entries must be made on 
the File Description and Extension sheets. Input specifications are not required. 



File Description Specifications 

The File Description sheet must describe both the indexed file to be processed 
and the record address file. The description of the indexed file to be processed 
must contain the following entries in addition to the other entries necessary to 
describe the file: 

File Description Specifications 




Column 28 must contain an L to indicate that the records are to be read from 
this file sequentially within limits. Enter an A in column 31 to indicate that 
record keys are used in processing the file. Enter an I in column 32 to indicate 
an indexed file. 

The record address file must be described with the following entries: 

File Description Specifications 




The name of the record address file must be entered in columns 7 through 14. 
Column 1 5 must contain an I to indicate that the file is an input file. Enter an R 
in column 16 to indicate that the file is a record address file. 
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All records in a file must be the same length. Thus, column 19 contains an F to 
indicate that the record length is fixed. 

A number equal to or a multiple of the disk record length must be entered in 
columns 20 through 23. This entry determines the size of the input/output area 
allocated by RPG II. For an explanation on block length calculation, seethe IBM 
System/3 Disk Concepts and Planning Guide, GC21 -7571 . If you want block 
length calculated for you by RPG II, assign a block length equal to the record 
length. By blocking disk records you can increase the input/output efficiency of 
your program by reducing the number of accesses. You must be sure, however, 
that enough main storage is available for your input/output area. 

Columns 24 through 27 must contain the length of the disk record. Key length, 
entered in columns 29 and 30, is the same length for all records in a file. The max- 
imum record key length is 29 characters. 

Whenever a disk file is described, DISK (Models 6, 10, and 15), DISK40 (Model 12 or 15), 
or DISK45 (Model 10, 12, or 15) is required in the Device columns. Since additional 
information is given on the Extension sheet, column 39 must contain an E. 



Extension Specifications 

To process a file using a record address file, two entries must be made on the Exten- 
sion sheet: 



RPG EXTENSION AND LINE COUNTER SPECIFICATIONS 

Punching j ^r.,|,h,c 
j Instruction ' Plll „- h 

Extension Specifications 




Columns 1 1 through 1 8 must contain the name of the record address file. The name 
must be the same as the record address file described on the File Description sheet. 

Columns 19 through 26 must contain the name of the file to be processed. This 
name must be the same filename defined on the File Description sheet. This entry 
indicates that the file is to be processed by the record address file coded in columns 
11 through 18. 



Example of Processing Sequentially within Limits 

You have a master customer file on disk consisting of 128-character records. The 
file is organized by customer number within customer class. Customers are sepa- 
rated into such classes as wholesalers or retailers. Together the customer number 
and class form a composite customer account number (key) in the form: ccnnnnn. 
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The customer class is cc and the customer number is nnnnn. Customer classes 
begin at 01 and are in ascending order. Within each customer class, customer 
numbers range from 00000-99999. 

You must prepare separate reports for each customer class for sales analysis pur- 
poses. A record address file can be used to supply the particular class categories 
and customer number ranges as shown in Figure 31. The key in each disk record 
begins in position 2, and the record address file is loaded in MFCU1. Figure 32 
shows the necessary File Description and Extension entries for this job. 



Record address file 
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Symbolic representation 
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Figure 31. Files for Processing Sequentially within Limits 
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